<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Getting Started
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot038.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot037.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot040.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc90">7.2</A>&nbsp;&nbsp;Getting Started</H2><UL>
<LI><A HREF="umsroot039.html#toc53">Creating a Module</A>
<LI><A HREF="umsroot039.html#toc54">Exporting</A>
<LI><A HREF="umsroot039.html#toc55">Importing</A>
<LI><A HREF="umsroot039.html#toc56">Definitions, Visibility and Accessibility</A>
</UL>

<A NAME="toc53"></A>
<H3 CLASS="subsection"><A NAME="htoc91">7.2.1</A>&nbsp;&nbsp;Creating a Module</H3>

You create a module simply by starting your program code with a
<A HREF="../bips/kernel/modules/module-1.html"><B>module/1</B></A><A NAME="@default315"></A>
directive. This should usually be placed at the beginning of the source file
and looks like
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- module(mymodule).
</PRE></BLOCKQUOTE>
As a rule, the module name should be chosen to be the same as the
file's base name (the filename without directory/folder and
suffix/extension part). E.g. the module <TT>mymodule</TT> might be
contained in a file <TT>mymodule.ecl</TT>.<BR>
<BR>
Anything you define in your module is by default <B>local</B> to that module.<BR>
<BR>
<A NAME="toc54"></A>
<H3 CLASS="subsection"><A NAME="htoc92">7.2.2</A>&nbsp;&nbsp;Exporting</H3>
<A NAME="@default316"></A>

A definition is made available to the outside world by <B>exporting</B> it.
All the exports of a module together form the module's <B>interface</B>.
Exporting is done with the
<A HREF="../bips/kernel/modules/export-1.html"><B>export/1</B></A><A NAME="@default317"></A>
directive, which can take
different forms depending on the kind of the exported item.<BR>
<BR>
Predicates are exported as follows:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- export p/2.

p(X,Y) :-
        ...
</PRE></BLOCKQUOTE>
Structures are exported by defining them with an
<A HREF="../bips/kernel/modules/export-1.html"><B>export/1</B></A><A NAME="@default318"></A>
instead of a
<A HREF="../bips/kernel/modules/local-1.html"><B>local/1</B></A><A NAME="@default319"></A>
directive, e.g.
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- export struct(book(author,title,publisher)).
</PRE></BLOCKQUOTE>
And the same holds for operators and other syntax settings:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- export op(500, xfx, before).
:- export chtab(0'$, lower_case).
:- export syntax_option(no_array_subscripts).
:- export macro(pretty/1, tr_pretty/2, []).
</PRE></BLOCKQUOTE>
All these declarations are valid locally in the module where they appear
<EM>and</EM> in every module that imports them.<BR>
<BR>
Initialization goals are exported as follows:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- export initialization(writeln("I have been imported")).
</PRE></BLOCKQUOTE>
Unlike the other declarations above, an exported
<A HREF="../bips/kernel/modules/export-1.html"><B>initialization/1</B></A><A NAME="@default320"></A> directive is <EM>not</EM> executed locally in
they module where it appears, but <EM>only</EM> in the context of the
module where it gets imported<SUP><A NAME="text4" HREF="umsroot037.html#note4">1</A></SUP>.<BR>
<BR>
<A NAME="toc55"></A>
<H3 CLASS="subsection"><A NAME="htoc93">7.2.3</A>&nbsp;&nbsp;Importing</H3>
<A NAME="@default321"></A>

In order to use a definition that has been exported elsewhere, it has
to be <B>imported</B>. Often it is desirable to import another module's
interface as a whole, i.e. everything it exports.
This is achieved by an
<A HREF="../bips/kernel/modules/import-1.html"><B>import/1</B></A><A NAME="@default322"></A>
directive of the form
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- import amodule.
</PRE></BLOCKQUOTE>
If the module is in a file and has to be compiled first, then
<A HREF="../bips/kernel/modules/use_module-1.html"><B>use_module/1</B></A><A NAME="@default323"></A>
can be used, which is a combination of
<A HREF="../bips/kernel/compiler/ensure_loaded-1.html"><B>ensure_loaded/1</B></A><A NAME="@default324"></A>
(see chapter <A HREF="umsroot028.html#chapcompiler">6</A>) and
<A HREF="../bips/kernel/modules/import-1.html"><B>import/1</B></A><A NAME="@default325"></A>:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- use_module("/home/util/amodule").
</PRE></BLOCKQUOTE>
If the module is a library in one of ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>'s library directories,
then it can be loaded and imported by
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- use_module(library(hash)).
</PRE></BLOCKQUOTE>
or simply using
<A HREF="../bips/kernel/compiler/lib-1.html"><B>lib/1</B></A><A NAME="@default326"></A> as in
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- lib(hash).
</PRE></BLOCKQUOTE>
It is also possible to import only a part of another module's
interface, using an
<A HREF="../bips/kernel/modules/import-1.html"><B>import-from directive</B></A><A NAME="@default327"></A>
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- import p/2 from amodule.
</PRE></BLOCKQUOTE>
Note that this is the only form of import that can refer to a module
that has not yet been loaded, and therefore allows a restricted form
of circularity in the import structure.<BR>
<BR>
<A NAME="toc56"></A>
<H3 CLASS="subsection"><A NAME="htoc94">7.2.4</A>&nbsp;&nbsp;Definitions, Visibility and Accessibility</H3>

For a given predicate name and arity the following rules hold:
<UL CLASS="itemize"><LI CLASS="li-itemize">
Every module can contain at most one <B>definition</B>
<A NAME="@default328"></A>
 <UL CLASS="itemize"><LI CLASS="li-itemize">
 this definition may be local or exported
 </UL>
<LI CLASS="li-itemize">In every module, at most one definition is <B>visible</B>
<A NAME="@default329"></A>
 <UL CLASS="itemize"><LI CLASS="li-itemize">
 if there is a definition in the module itself,
	this is also the visible one in the module
 <LI CLASS="li-itemize">otherwise, if there is an (unambiguous) import or reexport,
	this is the visible one
 <LI CLASS="li-itemize">otherwise no definition is visible
 </UL>
<LI CLASS="li-itemize">All exported definitions are <B>accessible</B> everywhere
<A NAME="@default330"></A>
 <UL CLASS="itemize"><LI CLASS="li-itemize">
 this might require explicit module qualification
	(see&nbsp;<A HREF="umsroot040.html#qualifiedaccess">7.3.2</A>)
 </UL>
</UL>
<HR>
<A HREF="umsroot038.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot037.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot040.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
